Creates a dialog box from a resource-based description.

DialogPtr GetNewDialog (
    SInt16 dialogID, 
    void *dStorage, 
    WindowPtr behind
);

dialogID

The resource ID of a dialog resource and an extended dialog resource. The resource IDs for both resources must be identical. If the dialog resource is missing, the Dialog Manager returns to your application without creating the requested dialog box. See ‘DLOG’ and ‘dlgx’ for a description of the dialog resource and the extended dialog resource, respectively.

dStorage

A pointer to the memory for the dialog structure. If you set this parameter to null, the Dialog Manager automatically allocates a nonrelocatable block in your application heap.

behind

A pointer to the window behind which the dialog box is to be placed on the desktop. Set this parameter to the window pointer (WindowPtr)-1L to bring the dialog box in front of all other windows.

function result

Returns a pointer to a dialog box. If none was created, returns null.

DISCUSSION

The GetNewDialog function creates a dialog structure from information in a dialog resource and an extended dialog resource (if it exists) and returns a pointer to the dialog structure. You can use this pointer with Window Manager or QuickDraw functions to manipulate the dialog box. If the dialog resource specifies that the dialog box should be visible, the dialog box is displayed. If the dialog resource specifies that the dialog box should initially be invisible, use the Window Manager function ShowWindow to display the dialog box.

The dialog resource contains a resource ID that specifies both the dialog box’s item list ('DITL') resource and its dialog font table ('dftb') resource. After calling the Resource Manager to read these resources into memory (if they are not already in memory), GetNewDialog makes a copy of the 'DITL' resource and uses that copy; thus you may have several dialog boxes with identical items.

If you supply a dialog color table ('dctb') resource with the same resource ID as the dialog resource, GetNewDialog uses NewColorDialog and returns a pointer to a color graphics port. If no dialog color table resource is present, GetNewDialog uses NewDialog to return a pointer to a black-and-white graphics port, although system software draws the window frame using the system’s default colors. However, if the Appearance Manager is available and the kDialogFlagsUseThemeBackground feature bit of the extended dialog resource is set, then the 'dctb' resource is ignored and a color graphics port is created.

SPECIAL CONSIDERATIONS

The GetNewDialog function doesn’t release the memory occupied by the resources. Therefore, your application should mark all resources used for a dialog box as purgeable or you should release the resources yourself.

If either the dialog resource or the item list resource can’t be read, the function result is null; your application should test to ensure that null is not returned before performing any more operations with the dialog box or its items.

As with all other windows, dialogs are created with an update region equal to their port rectangle. However, if the dialog’s 'DLOG' resource specifies that the dialog be made visible upon creation, the Dialog Manager draws the controls immediately and calls ValidRgn for each of their bounding rectangles. Other items are not drawn until the first update event for the dialog box is serviced.

If you need to display an alert box while your application is running in the background or is otherwise invisible to the user, call AEInteractWithUser

VERSION NOTES

This function was changed with Appearance Manager 1.0 to support the extended dialog ('dlgx') resource and the dialog font table ('dftb') resource.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.

© 2000 Apple Computer, Inc. — (Last Updated 4/14/2000)